home *** CD-ROM | disk | FTP | other *** search
/ Amiga Developer CD 2.1 / Amiga Developer CD v2.1.iso / NDK / NDK_3.5 / Documentation / Autodocs / amigaguide.doc < prev    next >
Encoding:
Text File  |  1999-04-13  |  25.5 KB  |  860 lines
  1. TABLE OF CONTENTS
  2.  
  3. amigaguide.library/--background--
  4. amigaguide.library/--rexxhost--
  5. amigaguide.library/AddAmigaGuideHostA
  6. amigaguide.library/AmigaGuideSignal
  7. amigaguide.library/CloseAmigaGuide
  8. amigaguide.library/GetAmigaGuideAttr
  9. amigaguide.library/GetAmigaGuideMsg
  10. amigaguide.library/GetAmigaGuideString
  11. amigaguide.library/LockAmigaGuideBase
  12. amigaguide.library/OpenAmigaGuideA
  13. amigaguide.library/OpenAmigaGuideAsyncA
  14. amigaguide.library/RemoveAmigaGuideHostA
  15. amigaguide.library/ReplyAmigaGuideMsg
  16. amigaguide.library/SendAmigaGuideCmdA
  17. amigaguide.library/SendAmigaGuideContextA
  18. amigaguide.library/SetAmigaGuideAttrsA
  19. amigaguide.library/SetAmigaGuideContextA
  20. amigaguide.library/UnlockAmigaGuideBase
  21. amigaguide.library/--background--           amigaguide.library/--background--
  22.  
  23.    PURPOSE
  24.         The amigaguide.library provides a means whereby developers
  25.         can easily add on-line help abilities to their applications.
  26.  
  27. amigaguide.library/--rexxhost--               amigaguide.library/--rexxhost--
  28.  
  29.    HOST INTERFACE
  30.         amigaguide.library provides an ARexx function host interface that
  31.         enables ARexx programs to take advantage of the features of
  32.         AmigaGuide. The functions provided by the interface are directly
  33.         related to the functions described herein, with the differences
  34.         mostly being in the way they are called.
  35.  
  36.         The function host library vector is located at offset -30 from
  37.         the library. This is the value you provide to ARexx in the
  38.         AddLib() function call.
  39.  
  40.    FUNCTIONS
  41.         ShowNode (PUBSCREEN,DATABASE,NODE,LINE,XREF)
  42.  
  43.         LoadXRef (NAME)
  44.  
  45.         GetXRef (NODE)
  46.  
  47.         AddXRef (WORD,FILE,LINE,TYPE)
  48.  
  49.         ExpungeXRef ()
  50.  
  51.    BUGS
  52.         V39, V40 and V41 did not support the ExpungeXRef() and
  53.         AddXRef() commands. This was fixed in V44.
  54.  
  55. amigaguide.library/AddAmigaGuideHostA   amigaguide.library/AddAmigaGuideHostA
  56.  
  57.     NAME
  58.         AddAmigaGuideHostA - Add a dynamic node host.           (V34)
  59.  
  60.     SYNOPSIS
  61.         handle = AddAmigaGuideHostA (hook, name, attrs);
  62.         d0                            a0    d0    a1
  63.  
  64.         AMIGAGUIDEHOST AddAmigaGuideHostA (struct Hook *, STRPTR,
  65.                                           struct TagItem *);
  66.  
  67.     FUNCTION
  68.         This function adds a callback hook to the dynamic node list.
  69.  
  70.         A dynamic node allows an application to incorporate context-
  71.         sensitive or live project data within their help system.
  72.  
  73.     INPUTS
  74.         hook - The callback hook.
  75.         name - Name of the AmigaGuideHost database that you are adding.
  76.             The name must be unique.
  77.         attrs - Additional attributes.  None are defined at this time.
  78.  
  79.     RETURNS
  80.         Returns NULL if unable to add the dynamic node host, otherwise
  81.         returns a pointer to a handle that will eventually be passed
  82.         to RemoveAmigaGuideHost() to remove the dynamic node host from
  83.         the list.
  84.  
  85.     NOTES
  86.         When AmigaGuide attempts to resolve a LINK command, it performs
  87.         the following sequence of events.
  88.  
  89.            Splits the name into a path, a database and a node (only
  90.              the node is required).
  91.            Opens the database.
  92.            Performs the following searches until the node is found:
  93.              Search the local database.
  94.              Search the local cross reference list.
  95.              Search the local dynamic node host.
  96.              Search the global help file (system help).
  97.              Search the global cross reference list.
  98.              Search the global dynamic node hosts.
  99.  
  100.     SEE ALSO
  101.         RemoveAmigaGuideHostA()
  102.  
  103.     EXAMPLE
  104.  
  105.         /* Hook dispatcher */
  106.         ULONG __asm hookEntry(
  107.                 register __a0 struct Hook *h,
  108.                 register __a2 VOID *obj,
  109.                 register __a1 VOID *msg)
  110.         {
  111.             /* Pass the parameters on the stack */
  112.             return ((h->h_SubEntry)(h, obj, msg));
  113.         }
  114.  
  115.         ULONG __saveds
  116.         dispatchAmigaGuideHost (struct Hook *h, STRPTR db, Msg msg)
  117.         {
  118.             struct opNodeIO *onm = (struct opNodeIO *) msg;
  119.             ULONG retval = 0;
  120.  
  121.             switch (msg->MethodID)
  122.             {
  123.                 /* Does this node belong to you? */
  124.                 case HM_FINDNODE:
  125.                     {
  126.                         struct opFindHost *ofh = (struct opFindHost *) msg;
  127.  
  128.                         kprintf("Find [%s] in %s\n", ofh->ofh_Node, db);
  129.  
  130.                         /* Return TRUE to indicate that it's your node,
  131.                          * otherwise return FALSE. */
  132.                          retval = TRUE;
  133.                     }
  134.                     break;
  135.  
  136.                 /* Open a node. */
  137.                 case HM_OPENNODE:
  138.                     kprintf("Open [%s] in %s\n", onm->onm_Node, db);
  139.  
  140.                     /* Provide the contents of the node */
  141.                     onm->onm_DocBuffer = TEMP_NODE;
  142.                     onm->onm_BuffLen   = strlen(TEMP_NODE);
  143.  
  144.                     /* Indicate that we were able to open the node */
  145.                     retval = TRUE;
  146.                     break;
  147.  
  148.                 /* Close a node, that has no users. */
  149.                 case HM_CLOSENODE:
  150.                     kprintf("Close [%s] in %s\n", onm->onm_Node, db);
  151.  
  152.                     /* Indicate that we were able to close the node */
  153.                     retval = TRUE;
  154.                     break;
  155.  
  156.                 /* Free any extra memory */
  157.                 case HM_EXPUNGE:
  158.                     kprintf("Expunge [%s]\n", db);
  159.                     break;
  160.  
  161.                 default:
  162.                     kprintf("Unknown method %ld\n", msg->MethodID);
  163.                     break;
  164.             }
  165.  
  166.             return (retval);
  167.         }
  168.  
  169.         main(int argc, char **argv)
  170.         {
  171.             struct Hook hook;
  172.             AMIGAGUIDEHOST hh;
  173.  
  174.             /* Open the library */
  175.             if (AmigaGuideBase = OpenLibrary("amigaguide.library", 33))
  176.             {
  177.                 /* Initialize the hook */
  178.                 hook.h_Entry    = hookEntry;
  179.                 hook.h_SubEntry = dispatchAmigaGuideHost;
  180.  
  181.                 /* Add the AmigaGuideHost to the system */
  182.                 if (hh = AddAmigaGuideHost(&hook, "ExampleHost", NULL))
  183.                 {
  184.                     /* Wait until we're told to quit */
  185.                     Wait(SIGBREAKF_CTRL_C);
  186.  
  187.                     /* Try removing the host */
  188.                     while (RemoveAmigaGuideHost(hh, NULL) > 0)
  189.                     {
  190.                         /* Wait a while */
  191.                         Delay(5);
  192.                     }
  193.                 }
  194.  
  195.                 /* close the library */
  196.                 CloseLibrary(AmigaGuideBase);
  197.             }
  198.         }
  199.  
  200.     BUGS
  201.         When a dynamic node host is first added it will receive a
  202.         HM_FINDNODE message with an onm_Node of "Main".  The
  203.         AGA_HelpGroup attribute will always be zero for this
  204.         particular message.
  205.  
  206. amigaguide.library/AmigaGuideSignal       amigaguide.library/AmigaGuideSignal
  207.  
  208.    NAME
  209.         AmigaGuideSignal - Obtain aysnc AmigaGuide signal.      (V34)
  210.  
  211.    SYNOPSIS
  212.         signal = AmigaGuideSignal ( handle );
  213.         d0                           a0
  214.  
  215.         ULONG AmigaGuideSignal (AMIGAGUIDECONTEXT);
  216.  
  217.    FUNCTION
  218.         This function returns the signal bit to Wait on for AmigaGuideMsg's
  219.         for a particular AmigaGuide database.
  220.  
  221.    INPUTS
  222.         handle -- Handle to a AmigaGuide system.
  223.  
  224.    EXAMPLE
  225.         ULONG sigw, sigh;
  226.         AMIGAGUIDECONTEXT handle;
  227.  
  228.         /* get the signal bit to wait on for a AmigaGuide message */
  229.         sigh = AmigaGuideSignal(handle);
  230.  
  231.         /* add the signal bit into the total signals to wait on */
  232.         sigw |= sigh;
  233.  
  234.    RETURNS
  235.         signal -- Signal bit to Wait on.
  236.  
  237.    SEE ALSO
  238.         OpenAmigaGuideAsyncA(), GetAmigaGuideMsg(), ReplyAmigaGuideMsg()
  239.  
  240. amigaguide.library/CloseAmigaGuide         amigaguide.library/CloseAmigaGuide
  241.  
  242.     NAME
  243.         CloseAmigaGuide - Close a AmigaGuide client.            (V34)
  244.  
  245.     SYNOPSIS
  246.         CloseAmigaGuide (handle);
  247.                           a0
  248.  
  249.         VOID CloseAmigaGuide (AMIGAGUIDECONTEXT);
  250.  
  251.     FUNCTION
  252.         Closes a synchronous, or asynchronous, AmigaGuide client.
  253.  
  254.         This function will also close all windows that were opened for
  255.         the client.
  256.  
  257.     INPUTS
  258.         handle - Handle to an AmigaGuide client.
  259.  
  260.     SEE ALSO
  261.         OpenAmigaGuideA(), OpenAmigaGuideAsyncA()
  262.  
  263. amigaguide.library/GetAmigaGuideAttr     amigaguide.library/GetAmigaGuideAttr
  264.  
  265.     NAME
  266.         GetAmigaGuideAttr - Get an AmigaGuide attribute.        (V34)
  267.  
  268.     SYNOPSIS
  269.         retval = GetAmigaGuideAttr (tag, handle, storage);
  270.         d0                           d0    a0      a1
  271.  
  272.         LONG GetAmigaGuideAttr (Tag, AMIGAGUIDECONTEXT, ULONG *);
  273.  
  274.     FUNCTION
  275.         This function is used to obtain attributes from AmigaGuide.
  276.  
  277.     INPUTS
  278.         tag - Attribute to obtain.
  279.         handle - Handle to an AmigaGuide system.
  280.         storage - Pointer to appropriate storage for the answer.
  281.  
  282.     TAGS
  283.         AGA_Path (BPTR) - Pointer to the current path used by
  284.             AmigaGuide.
  285.  
  286.         AGA_XRefList (struct List *) - Pointer to the current
  287.             cross reference list.
  288.  
  289.     RETURNS
  290.  
  291.     SEE ALSO
  292.         SetAmigaGuideAttrsA()
  293.  
  294. amigaguide.library/GetAmigaGuideMsg       amigaguide.library/GetAmigaGuideMsg
  295.  
  296.    NAME
  297.         GetAmigaGuideMsg - Receive async AmigaGuide message.    (V34)
  298.  
  299.    SYNOPSIS
  300.         msg = GetAmigaGuideMsg (handle);
  301.         d0                       a0
  302.  
  303.         struct AmigaGuideMsg *GetAmigaGuideMsg (AMIGAGUIDECONTEXT);
  304.  
  305.    FUNCTION
  306.         This function returns a SIPC message from the AmigaGuide system,
  307.         if there is a message available.
  308.  
  309.    INPUTS
  310.         handle - Handle to a AmigaGuide system.
  311.  
  312.    EXAMPLE
  313.  
  314.         AMIGAGUIDECONTEXT handle;
  315.         struct AmigaGuideMsg *agm;
  316.  
  317.         /* get a AmigaGuide message */
  318.         while (agm = GetAmigaGuideMsg(handle))
  319.         {
  320.             /* process the event */
  321.             switch (agm->agm_Type)
  322.             {
  323.                 case ToolCmdReplyID: /* a command has completed */
  324.                     if (agm->agm_Pri_Ret)
  325.                     {
  326.                         /* An error occurred, the reason is in agm_Sec_Ret.
  327.                          * The command string is in agm_Data
  328.                          */
  329.                     }
  330.                     break;
  331.  
  332.                 case ToolStatusID: /* status message */
  333.                     if (agm->agm_Pri_Ret)
  334.                     {
  335.                         /* an error occurred, the reason is in agm_Sec_Ret */
  336.                     }
  337.                     break;
  338.  
  339.                 default:
  340.                     break;
  341.             }
  342.  
  343.             /* reply to the AmigaGuide message */
  344.             ReplyAmigaGuideMsg(agm);
  345.         }
  346.  
  347.    RETURNS
  348.         msg -- Pointer to a SIPC message or NULL if no message was
  349.             available.
  350.  
  351.    SEE ALSO
  352.         OpenAmigaGuideAsyncA(), AmigaGuideSignal(), ReplyAmigaGuideMsg()
  353.  
  354. amigaguide.library/GetAmigaGuideString amigaguide.library/GetAmigaGuideString
  355.  
  356.    NAME
  357.         GetAmigaGuideString - Get an AmigaGuide string.
  358.                                                                (V34)
  359.    SYNOPSIS
  360.         txt = GetAmigaGuideString (id);
  361.         d0                         d0
  362.  
  363.         STRPTR GetAmigaGuideString (ULONG);
  364.  
  365.    FUNCTION
  366.         This function is used to obtain a localized string given the
  367.         ID.
  368.  
  369.    INPUTS
  370.         ID -- Valid AmigaGuide string id.
  371.  
  372.    RETURNS
  373.         A pointer to the string.   NULL for an invalid string.
  374.  
  375.    SEE ALSO
  376.  
  377. amigaguide.library/LockAmigaGuideBase   amigaguide.library/LockAmigaGuideBase
  378.  
  379.     NAME
  380.         LockAmigaGuideBase - Lock an AmigaGuide client.         (V34)
  381.  
  382.     SYNOPSIS
  383.         key = LockAmigaGuideBase (AMIGAGUIDECONTEXT handle);
  384.         d0                                            a0
  385.  
  386.         LONG LockAmigaGuideBase (AMIGAGUIDECONTEXT);
  387.  
  388.     FUNCTION
  389.         This function is used to lock the AmigaGuide context handle
  390.         while working with data obtained with the the
  391.         GetAmigaGuideAttr() function.
  392.  
  393.     INPUTS
  394.         handle - AMIGAGUIDECONTEXT handle obtained with
  395.             OpenAmigaGuideAsync().
  396.  
  397.     RETURNS
  398.         Returns a key to pass to UnlockAmigaGuideBase().
  399.  
  400.     SEE ALSO
  401.         UnlockAmigaGuideBase()
  402.  
  403. amigaguide.library/OpenAmigaGuideA         amigaguide.library/OpenAmigaGuideA
  404.  
  405.     NAME
  406.         OpenAmigaGuideA - Open a synchronous AmigaGuide database.
  407.  
  408.     SYNOPSIS
  409.         handle = OpenAmigaGuideA (nag, attrs);
  410.         d0                         a0   a1
  411.  
  412.         AMIGAGUIDECONTEXT OpenAmigaGuideA (struct NewAmigaGuide *,
  413.                                            struct TagItem *);
  414.  
  415.         handle = OpenAmigaGuide (nag, tag1, ...);
  416.  
  417.         AMIGAGUIDECONTEXT OpenAmigaGuide (struct NewAmigaGuide *,
  418.                                           Tag tag1, ...);
  419.  
  420.     FUNCTION
  421.         Opens a AmigaGuide database, complete with the first viewing
  422.         window, for synchronous activity.
  423.  
  424.         Before you call OpenAmigaGuide(), you must initialize a NewAmigaGuide
  425.         structure.  NewAmigaGuide is a structure that contains all the
  426.         information needed to open a database.  The NewAmigaGuide structure
  427.         must be retained until the call returns.
  428.  
  429.         The function will not return until the user closes all the
  430.         windows.
  431.  
  432.     INPUTS
  433.         nag - Pointer to an instance of a NewAmigaGuide structure.  That
  434.             structure is initialized with the following data.
  435.  
  436.                   nag_Lock
  437.                   Lock on the directory that the database is located in.
  438.                   Not needed if nag_Name contains the complete path name.
  439.  
  440.                   nag_Name
  441.                   Name of the AmigaGuide database.
  442.  
  443.                   nag_Screen
  444.                   Screen to open the viewing windows on, NULL for the
  445.                   Workbench screen.
  446.  
  447.                   nag_PubScreen
  448.                   Pointer to the name of the public screen to open on.
  449.                   Must already be opened.
  450.  
  451.                   nag_HostPort
  452.                   Name of the applications' ARexx port (currently not used).
  453.  
  454.                   nag_ClientPort
  455.                   Base name to use for the databases' ARexx port.
  456.  
  457.                   nag_Flags
  458.                   Used to specify the requirements of this database.  The
  459.                   flags are defined in <libraries/amigaguide.h>.
  460.  
  461.                   nag_Context
  462.                   NULL terminated array of context nodes, in the form of:
  463.  
  464.                         /* context array */
  465.                         STRPTR context[] =
  466.                         {
  467.                             "MAIN",
  468.                             "INTRO",
  469.                             "GADGETS",
  470.                             NULL
  471.                         };
  472.  
  473.                   The context array is not copied, but referenced,
  474.                   therefore must remain static throughout the useage of
  475.                   the AmigaGuide system.  This array is only referenced
  476.                   when using the SetAmigaGuideContext() function.
  477.  
  478.                   nag_Node
  479.                   Node to start at (does not work with OpenAmigaGuideAsync())
  480. .
  481.  
  482.                   nag_Line
  483.                   Line to start at (does not work with OpenAmigaGuideAsync())
  484. .
  485.  
  486.                   nag_Extens
  487.                   Used by V37 and beyond to pass additional arguments.
  488.  
  489.                   nag_Client
  490.                   This is a private pointer, MUST be initialized to NULL.
  491.  
  492.         attrs - Additional attributes.
  493.  
  494.     TAGS
  495.         AGA_HelpGroup (ULONG) -- Unique identifier used to identify the
  496.             AmigaGuide help windows.  See OpenWindow() and GetUniqueID().
  497.  
  498.             Default for this tag is NULL.  Applicability is (I). (V39)
  499.  
  500.     EXAMPLE
  501.  
  502.         /* Short example showing synchronous AmigaGuide access */
  503.         LONG ShowAmigaGuideFile (STRPTR name, STRPTR node, LONG line)
  504.         {
  505.             struct NewAmigaGuide nag = {NULL};
  506.             AMIGAGUIDECONTEXT handle;
  507.             LONG retval = 0L;
  508.  
  509.             /* Fill in the NewAmigaGuide structure */
  510.             nag.nag_Name = name;
  511.             nag.nag_Node = node;
  512.             nag.nag_Line = line;
  513.  
  514.             /* Open the AmigaGuide client */
  515.             if ( handle = OpenAmigaGuide(&nag, NULL))
  516.             {
  517.                 /* Close the AmigaGuide client */
  518.                 CloseAmigaGuide(handle);
  519.             }
  520.             else
  521.             {
  522.                 /* Get the reason for failure */
  523.                 retval = IoErr();
  524.             }
  525.  
  526.             return (retval);
  527.         }
  528.  
  529.     RETURNS
  530.         handle - Handle to a AmigaGuide system.
  531.  
  532.     SEE ALSO
  533.         OpenAmigaGuideAsyncA(), CloseAmigaGuide()
  534.  
  535. amigaguide.library/OpenAmigaGuideAsyncAmigaguide.library/OpenAmigaGuideAsyncA
  536.  
  537.    NAME
  538.         OpenAmigaGuideAsyncA - Open an AmigaGuide database async (V34)
  539.  
  540.    SYNOPSIS
  541.         handle = OpenAmigaGuideAsyncA (nag, attrs);
  542.         d0                              a0   d0
  543.  
  544.         AMIGAGUIDECONTEXT OpenAmigaGuideAsyncA (struct NewAmigaGuide *,
  545.                                                 struct TagItem *);
  546.  
  547.         handle = OpenAmigaGuideAsync (nag, tag1, ...);
  548.  
  549.         AMIGAGUIDECONTEXT OpenAmigaGuideAsyncA (struct NewAmigaGuide *,
  550.                                                 Tag tag1, ...);
  551.  
  552.    FUNCTION
  553.         Opens an AmigaGuide database for ansynchronous use.
  554.  
  555.         The NewAmigaGuide structure, and its pointers, must stay valid until
  556.         an ActiveToolID or ToolStatusID message is received by the calling
  557.         process.
  558.  
  559.         This function actually spawns OpenAmigaGuide() as another process,
  560.         so, for further documentation, refer to the OpenAmigaGuide()
  561.         function.
  562.  
  563.    INPUTS
  564.         nag -- Pointer to a valid NewAmigaGuide structure.
  565.             (see OpenAmigaGuide() for documentation on its useage).
  566.  
  567.         attrs -- Additional attributes.  See OpenAmigaGuideA().
  568.  
  569.    RETURNS
  570.         handle -- Handle to an AmigaGuide system.
  571.  
  572.    SEE ALSO
  573.         OpenAmigaGuideA(), CloseAmigaGuide()
  574.  
  575. amigaguide.library/RemoveAmigaGuideHostAgaguide.library/RemoveAmigaGuideHostA
  576.  
  577.     NAME
  578.         RemoveAmigaGuideHostA - Remove a dynamic node host.     (V34)
  579.  
  580.     SYNOPSIS
  581.         use = RemoveAmigaGuideHostA (key, attrs)
  582.         d0                            a0   a1
  583.  
  584.         LONG RemoveAmigaGuideHostA (AMIGAGUIDEHOST, struct TagItem *);
  585.  
  586.         use = RemoveAmigaGuideHost (key, tag1, ...);
  587.  
  588.         LONG RemoveAmigaGuideHost (AMIGAGUIDEHOST, Tag, ...);
  589.  
  590.     FUNCTION
  591.         This function removes a dynamic node host, that was added by
  592.         AddAmigaGuideHost(), from the system.
  593.  
  594.     INPUTS
  595.         key - Key that was returned by AddAmigaGuideHost().
  596.  
  597.         attrs - Additional attributes.  None are defined at this time.
  598.  
  599.     RETURNS
  600.         use - Number of outstanding clients of this database.  You
  601.             can not exit until use==0.
  602.  
  603.     SEE ALSO
  604.         AddAmigaGuideHostA()
  605.  
  606. amigaguide.library/ReplyAmigaGuideMsg   amigaguide.library/ReplyAmigaGuideMsg
  607.  
  608.    NAME
  609.         ReplyAmigaGuideMsg - Reply to an AmigaGuide message.    (V34)
  610.  
  611.    SYNOPSIS
  612.         ReplyAmigaGuideMsg ( msg );
  613.                              a0
  614.  
  615.         VOID ReplyAmigaGuideMsg (struct AmigaGuideMsg *msg);
  616.  
  617.    FUNCTION
  618.         This function is used to reply to an AmigaGuide SIPC message.
  619.  
  620.    INPUTS
  621.         msg - Pointer to a SIPC message returned by a previous call to
  622.             GetAmigaGuideMsg().
  623.  
  624.    SEE ALSO
  625.         OpenAmigaGuideAsyncA(), AmigaGuideSignal(), GetAmigaGuideMsg()
  626.  
  627. amigaguide.library/SendAmigaGuideCmdA   amigaguide.library/SendAmigaGuideCmdA
  628.  
  629.    NAME
  630.         SendAmigaGuideCmdA - Send a command string to AmigaGuide (V34)
  631.  
  632.    SYNOPSIS
  633.         success = SendAmigaGuideCmdA (handle, cmd, attrs );
  634.           d0                            a0    d0   d1
  635.  
  636.         BOOL SendAmigaGuideCmdA (AMIGAGUIDECONTEXT, STRPTR, struct TagItem *)
  637. ;
  638.  
  639.         success = SendAmigaGuideCmd (handle, cmd, tag1, ...);
  640.  
  641.         BOOL SendAmigaGuideCmd (AMIGAGUIDECONTEXT, STRPTR, Tag);
  642.  
  643.    FUNCTION
  644.         This function sends a command string to an AmigaGuide system.  The
  645.         command can consist of any valid AmigaGuide action command.
  646.  
  647.         The following are the currently valid action commands:
  648.  
  649.         ALINK <name> - Load the named node into a new window.
  650.  
  651.         LINK <name> - Load the named node.
  652.  
  653.         RX <macro> - Execute an ARexx macro.
  654.  
  655.         RXS <cmd> - Execute an ARexx string file.  To display a picture,
  656.             use 'ADDRESS COMMAND DISPLAY <picture name>', to
  657.             display a text file 'ADDRESS COMMAND MORE <doc>'.
  658.  
  659.         CLOSE - Close the window (should only be used on windows
  660.             that were started with ALINK).
  661.  
  662.         QUIT - Shutdown the current database.
  663.  
  664.    INPUTS
  665.         handle - Handle to an AmigaGuide system.
  666.  
  667.         cmd - Command string.
  668.  
  669.         attrs - Future expansion, must be set to NULL for now.
  670.  
  671.    TAGS
  672.         AGA_Context (ULONG) - Data is used as an index into nag_Context
  673.             array.  This is used to build and send a LINK command.
  674.  
  675.    EXAMPLE
  676.  
  677.         /* bring up help on a particular subject */
  678.         SendAmigaGuideCmd(handle, "LINK MAIN", NULL);
  679.  
  680.    RETURNS
  681.         Returns TRUE if the message was sent, otherwise returns FALSE.
  682.  
  683.    BUGS
  684.         ALINK does not open a new window when using V39.
  685.  
  686.    SEE ALSO
  687.  
  688. amigaguide.library/SendAmigaGuideContextAguide.library/SendAmigaGuideContextA
  689.  
  690.    NAME
  691.         SendAmigaGuideContextA - Align an AmigaGuide system on the context ID
  692. .
  693.                                                                (V34)
  694.    SYNOPSIS
  695.         success = SendAmigaGuideContextA (handle, attrs);
  696.         d0                                 a0      d0
  697.  
  698.         BOOL SendAmigaGuideContextA (AMIGAGUIDECONTEXT, struct TagItem *);
  699.  
  700.         success = SendAmigaGuideContext (handle, tag1, ...);
  701.  
  702.         BOOL SendAmigaGuideContext (AMIGAGUIDECONTEXT, Tag, ...);
  703.  
  704.    FUNCTION
  705.         This function is used to send a message to an AmigaGuide system to
  706.         align it on the current context ID.
  707.  
  708.         This function effectively does a:
  709.  
  710.             SendAmigaGuideCmd(handle 'LINK ContextArray[contextID]', NULL);
  711.  
  712.    INPUTS
  713.         handle - Handle to an AmigaGuide system.
  714.         future - Future expansion, must be set to NULL for now.
  715.  
  716.    EXAMPLE
  717.  
  718.         struct IntuiMessage *imsg;
  719.  
  720.         ...
  721.  
  722.         case RAWKEY:
  723.             switch (imsg->Code)
  724.             {
  725.                 case 95:
  726.                     /* bring up help on a particular subject */
  727.                     SendAmigaGuideContext(handle, NULL);
  728.                     break;
  729.                 ...
  730.             }
  731.             break;
  732.  
  733.         ...
  734.  
  735.    RETURNS
  736.         success -- Returns TRUE if the message was sent, otherwise returns
  737.             FALSE.
  738.  
  739.    SEE ALSO
  740.         SetAmigaGuideContextA(), SendAmigaGuideCmdA()
  741.  
  742. amigaguide.library/SetAmigaGuideAttrsA amigaguide.library/SetAmigaGuideAttrsA
  743.  
  744.     NAME
  745.         SetAmigaGuideAttrsA - Set an AmigaGuide attribute.      (V34)
  746.  
  747.     SYNOPSIS
  748.         retval = SetAmigaGuideAttrsA (handle, attrs);
  749.         d0                             a0      a1
  750.  
  751.         LONG SetAmigaGuideAttrsA (AMIGAGUIDECONTEXT, struct TagItem *);
  752.  
  753.         retval = SetAmigaGuideAttrs (handle, tag1, ...);
  754.  
  755.         LONG SetAmigaGuideAttrs (AMIGAGUIDECONTEXT, Tag, ...);
  756.  
  757.     FUNCTION
  758.         This function is used to set AmigaGuide attributes.
  759.  
  760.     INPUTS
  761.         handle -- Pointer to an AmigaGuide handle.
  762.  
  763.         attrs -- Attribute pairs to set.
  764.  
  765.     TAGS
  766.         AGA_Activate (BOOL) - AmigaGuide activates the window when
  767.             it receives a LINK command.  This tag allows the
  768.             application developer to turn that feature off and on.
  769.  
  770.     SEE ALSO
  771.         GetAmigaGuideAttr()
  772.  
  773. amigaguide.library/SetAmigaGuideContextAgaguide.library/SetAmigaGuideContextA
  774.  
  775.    NAME
  776.         SetAmigaGuideContextA - Set the context ID for an AmigaGuide system.
  777.                                                                (V34)
  778.    SYNOPSIS
  779.         success = SetAmigaGuideContextA ( handle, context, attrs );
  780.         d0                                 a0       d0      d1
  781.  
  782.         BOOL SetAmigaGuideContextA (AMIGAGUIDECONTEXT, ULONG,
  783.                                     struct TagItem *);
  784.  
  785.         success = SetAmigaGuideContext (handle, context, tag1, ...);
  786.  
  787.         BOOL SetAmigaGuideContext (AMIGAGUIDECONTEXT, ULONG, Tag, ...);
  788.  
  789.    FUNCTION
  790.         This function, and the SendAmigaGuideContext() function, are used to
  791.         provide a simple way to display a node based on a numeric value,
  792.         instead of having to build up a slightly more complex command
  793.         string.
  794.  
  795.    INPUTS
  796.         handle -- Handle to an AmigaGuide system.
  797.  
  798.         context -- Index value of the desired node to display.
  799.  
  800.         future -- Future expansion, must be set to NULL for now.
  801.  
  802.    EXAMPLE
  803.  
  804.         /* sample context table */
  805.         STRPTR ContextArray[] =
  806.         {
  807.             "MAIN",
  808.             "FILEREQ",
  809.             "PRINT",
  810.             "ABOUT",
  811.             NULL
  812.         };
  813.  
  814.         /* quickie defines */
  815.         #define HELP_MAIN      0
  816.         #define HELP_FILEREQ   1
  817.         #define HELP_PRINT     2
  818.         #define HELP_ABOUT     3
  819.  
  820.         ...
  821.  
  822.         struct NewAmigaGuide nag = {NULL};
  823.  
  824.         /* initialize the context table */
  825.         nag.nag_Context = ContextArray;
  826.  
  827.         ...
  828.  
  829.         /* bring up help on a particular subject */
  830.         SetAmigaGuideContext(handle, HELP_ABOUT, NULL);
  831.  
  832.    RETURNS
  833.         success - Returns TRUE if a valid context ID was passed,
  834.             otherwise returns FALSE.
  835.  
  836.    SEE ALSO
  837.         SendAmigaGuideContextA(), SendAmigaGuideCmdA()
  838.  
  839. amigaguide.library/UnlockAmigaGuideBasemigaguide.library/UnlockAmigaGuideBase
  840.  
  841.     NAME
  842.         UnlockAmigaGuideBase - Unlock an AmigaGuide client.     (V34)
  843.  
  844.     SYNOPSIS
  845.         UnlockAmigaGuideBase (key);
  846.                               d0
  847.  
  848.         VOID UnlockAmigaGuideBase (LONG);
  849.  
  850.     FUNCTION
  851.         This function is used to release a lock obtained with
  852.         LockAmigaGuideBase().
  853.  
  854.     INPUTS
  855.         key - Value returned by LockAmigaGuideBase().
  856.  
  857.     SEE ALSO
  858.         LockAmigaGuideBase().
  859.  
  860.